Serve OpenAPI 3.0 spec at /openapi.v1.json by myers · Pull Request #37038 · go-gitea/gitea

myers · 2026-03-30T03:38:21Z

Add a build-time conversion step that transforms the existing Swagger 2.0 spec into an OpenAPI 3.0 spec. The OAS3 spec is served alongside the existing Swagger 2.0 spec, enabling API clients that require OAS3 (progenitor, openapi-python-client, etc.) to generate code directly from Gitea's API.

New files:

build/generate-openapi.go — converts swagger v1_json.tmpl to OAS3
build/openapi3-tools.go — tool dependency for kin-openapi
routers/web/swagger_json.go — serves the OAS3 spec
templates/swagger/v1_openapi3_json.tmpl — generated OAS3 spec

This is not to be an answer to how gitea handles OAS3 long term, but a way to use what we have to move a step forward.

See https://github.com/myers/gt for how this can be used.

Written with Claude Code using Opus, and human reviewed.

wxiaoguang · 2026-03-30T06:56:15Z

Can you add more comments and document more details in the tool's code? For example: why it needs knownEnumTypes mapping? etc.

silverwind · 2026-03-30T08:13:31Z

Makefile

+		printf "%s" "$${diff}"; \
+		exit 1; \
+	fi
+


Remove the 3 in target and variable names as well as templates/swagger/v1_openapi3_json.tmpl. We don't specify a swagger version either so this is consistent and simpler.

Swagger is openapi2. I think having "3" on the openapi names makes it clear what we are talking about.

silverwind · 2026-03-30T08:52:51Z

I think we should probably also evaluate using OAS3 for swagger-ui. Long-term I would like us to move completely to a OAS3-based solution, ideally OAS 3.1.

Copilot

Pull request overview

Adds an OpenAPI 3.0 (OAS3) JSON spec endpoint generated at build-time by converting the existing Swagger 2.0 template, so API clients that require OAS3 can generate SDKs directly while keeping the existing Swagger v1 spec.

Changes:

Serve an OAS3 spec at /openapi.v1.json alongside the existing /swagger.v1.json.
Add a generator (build/generate-openapi.go) to convert templates/swagger/v1_json.tmpl → templates/swagger/v1_openapi3_json.tmpl.
Wire generation + consistency checks into make generate-swagger / backend checks and add required Go module dependencies.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
routers/web/web.go	Registers the new `/openapi.v1.json` route when Swagger is enabled.
routers/web/swagger_json.go	Adds the `OpenAPI3Json` handler to render the OAS3 JSON template.
build/generate-openapi.go	Implements Swagger2→OAS3 conversion and post-processing/enrichment steps.
build/openapi3-tools.go	Attempts to pin kin-openapi tool deps for generation.
templates/swagger/v1_openapi3_json.tmpl	Generated OAS3 JSON template served by the new route.
Makefile	Adds OpenAPI3 generation/check targets and hooks into existing checks.
go.mod / go.sum	Adds kin-openapi and related transitive deps.
.editorconfig	Adds formatting rules for the generated OAS3 template.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Makefile

build/generate-openapi.go

build/openapi3-tools.go

TheFox0x7 · 2026-03-30T09:00:21Z

I think we should probably also evaluate using OAS3 for swagger-ui. Long-term I would like us to move completely to a OAS3-based solution, ideally OAS 3.1.

IMO this should be one step. Displaying spec that's converted from generated one does not feel right to me. It's a step too much in the pipeline and I'd prefer to be closer to what we directly control. I'll try to get back to generating API directly from structs after I'll finish dealing with my package related PRs as I'm tied up there a bit.

silverwind · 2026-03-30T17:23:37Z

BTW I would make it just openapi.json, there will never be a v2, the naming of the swagger file is legacy but should be kept.

TheFox0x7 · 2026-03-30T17:35:14Z

what about v4 which is supposedly in works?

silverwind · 2026-03-30T17:38:55Z

No idea about that , but I don't think anyone wants to maintain multiple versions of the api existing at the same time in the same repo, that's more like wishful thinking.

silverwind · 2026-03-30T18:32:09Z

But I guess keep the v1 for consistency with swagger and the unlikely event that there will be v2+.

silverwind · 2026-04-03T23:51:11Z

Regarding knownEnumTypes two better ideas:

Create a small AST walker to extract the enums
Leave the enums as-is, e.g. inline

Add a build-time conversion step that transforms the existing Swagger 2.0 spec into an OpenAPI 3.0 spec. The OAS3 spec is served alongside the existing Swagger 2.0 spec, enabling API clients that require OAS3 (progenitor, openapi-python-client, etc.) to generate code directly from Gitea's API. New files: - build/generate-openapi.go — converts swagger v1_json.tmpl to OAS3 - build/openapi3-tools.go — tool dependency for kin-openapi - routers/web/swagger_json.go — serves the OAS3 spec - templates/swagger/v1_openapi3_json.tmpl — generated OAS3 spec

- Add build/generate-openapi.go as Makefile prerequisite so changes to the converter trigger spec regeneration - Remove leftover `_ = key` no-op statement - Add top-of-file comment explaining what the converter does and why - Document why knownEnumTypes mapping is needed Co-Authored-By: Claude Opus 4 (claude-opus-4-6)

myers · 2026-04-11T17:41:49Z

Regarding knownEnumTypes two better ideas:
1. Create a small AST walker to extract the enums

2. Leave the enums as-is, e.g. inline

SDK generators like progenitor (Rust) need named enum types to produce good code. Without them, you get duplicate anonymous string types on every field instead of a shared StateType enum. Deduplicating enums and giving them proper names in #/components/schemas/ is the main motivation for the converter.

AST Walker: Walk Go source to find type StateType string declarations and extract the real type names. This would eliminate the map entirely and be correct by construction. But it's a significant scope increase — needs to parse Go source files, resolve which types are actually used in swagger-annotated structs, and handle edge cases.

Worth doing eventually but feels like a separate PR.

Or maybe better to focus efforts on building a better go annotations to OpenAPI 3 spec.

My goal here was the shortest path to being able to use OpenAPI ecosystem tools.

myers · 2026-04-11T17:43:31Z

IMO this should be one step. Displaying spec that's converted from generated one does not feel right to me. I

I understand the concern — a two-stage pipeline (annotations → Swagger 2.0 → OAS3) is more steps than ideal. But I think this PR is a useful incremental step:

It helps now — SDK generators and tooling that require OAS3 can consume Gitea's API today, without waiting for a better tool.
It doesn't block the direct approach — when someone builds direct OAS3 generation from structs, this converter simply gets deleted. No tech debt accumulates because the converter is a standalone build tool with no runtime footprint
The conversion is build-time only — the generated spec is committed as a template, so there's no runtime overhead or dependency on kin-openapi in the Gitea binary

That said, direct OAS3 generation would be strictly better long-term.

myers · 2026-04-11T17:45:55Z

@silverwind @TheFox0x7 I made some changes. Could we move forward with this?

If we don't want to move forward with this can you give me a path to get an openapi 3.x spec that you do like?

TheFox0x7 · 2026-04-11T18:22:52Z

Could we move forward with this?

Have you addressed reviews?

myers · 2026-04-12T21:25:21Z

Could we move forward with this?

Have you addressed reviews?

I had missed some, thank you for the prompt.

The enumGroups loop declared key but never used it; use _ instead so the generator compiles. Regenerate v1_openapi3_json.tmpl. Co-Authored-By: Claude (Opus)

GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Mar 30, 2026

github-actions bot added modifies/go Pull requests that update Go code modifies/templates This PR modifies the template files modifies/internal modifies/dependencies labels Mar 30, 2026

silverwind reviewed Mar 30, 2026

View reviewed changes

silverwind requested a review from Copilot March 30, 2026 08:50

Copilot started reviewing on behalf of silverwind March 30, 2026 08:50 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

Makefile Outdated Show resolved Hide resolved

build/generate-openapi.go Outdated Show resolved Hide resolved

build/openapi3-tools.go Show resolved Hide resolved

myers added 2 commits April 11, 2026 17:37

myers force-pushed the feat/openapi3-conversion branch from e6f384f to e9cd8cf Compare April 11, 2026 17:43

Fix unused variable error in OpenAPI generator

4faceec

The enumGroups loop declared key but never used it; use _ instead so the generator compiles. Regenerate v1_openapi3_json.tmpl. Co-Authored-By: Claude (Opus)

Uh oh!

Conversation

myers commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wxiaoguang commented Mar 30, 2026

Uh oh!

silverwind Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myers Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

silverwind commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheFox0x7 commented Mar 30, 2026

Uh oh!

silverwind commented Mar 30, 2026

Uh oh!

TheFox0x7 commented Mar 30, 2026

Uh oh!

silverwind commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

silverwind commented Mar 30, 2026

Uh oh!

silverwind commented Apr 3, 2026

Uh oh!

myers commented Apr 11, 2026

Uh oh!

myers commented Apr 11, 2026

Uh oh!

myers commented Apr 11, 2026

Uh oh!

TheFox0x7 commented Apr 11, 2026

Uh oh!

myers commented Apr 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

myers commented Mar 30, 2026 •

edited

Loading

silverwind Mar 30, 2026 •

edited

Loading

silverwind commented Mar 30, 2026 •

edited

Loading

silverwind commented Mar 30, 2026 •

edited

Loading